home *** CD-ROM | disk | FTP | other *** search
/ Info-Mac 3 / Info_Mac_1994-01.iso / Development / General / Gestalt Value Library / GestaltValue Read Me < prev    next >
Text File  |  1992-06-24  |  5KB  |  61 lines

  1. GestaltValue Read Me -- June 24, 1992
  2. © Copyright 1992 Apple Computer, Inc.
  3. All rights reserved
  4. ------------------------------------
  5. This document describes the GestaltValue functionality as implemented in GestaltValue.o.  Interfaces to GestaltValue are provided in GestaltValue.h and GestaltValue.p.
  6.  
  7. GestaltValue is a set of routines, implemented as glue, that extend and  enhance existing Gestalt functionality.  For a complete description of Gestalt, refer to Chapter 3 of Inside Macintosh VI. 
  8.  
  9. Rationale
  10.  
  11. Existing Gestalt functionality allows developers to put Gestalt to use in their own applications by register a Gestalt selector with using the NewGestalt or ReplaceGestalt calls, and providing a function which can return the appropriate response.
  12.  
  13. While this is a powerful feature of Gestalt, in practice, it is difficult to take advantage of for a number of reasons:
  14.  
  15. 1) The supplied function must entirely reside in the system heap.
  16.  
  17. 2) The function should be reentrant and not move memory because Gestalt (and therefore the function) may be called at interrupt time.
  18.  
  19. 3) The function must effectively remain resident until restart.  This is a problem for applications which may come and go multiple times.
  20.  
  21. 4) Since the purpose of the function is to return a response value, the function must know how to locate, or otherwise manage that value.
  22.  
  23. All of this means a lot of work just to allow code to retrieve the response value via Gestalt.
  24.  
  25. GestaltValue addresses all these issues.  It is built to deal with the most common case, simply returning a 32-bit value.  It safely implements and installs a single common, shared gestalt function and reports back values via the existing Gestalt mechanism.  This gestalt function gets installed the first time the glue gets invoked.  Subsequent calls to the glue (either from the same application, or a different one) cooperate with the gestalt function to maintain a table of selectors and values for the function to report.
  26.  
  27. GestaltValue will eventually be implemented as a standard system trap, in which case, the glue will simply call the trap.  Although currently provided as a standalone object file, GestaltValue will eventually be rolled into development libraries; watch for it in a development system near you.
  28.  
  29. All three GestaltValue functions defined below can move memory, so they cannot be called at interrupt time.  But the shared gestalt function that GestaltValue installs in the system heap is reentrant and does not move memory (i.e., it satisfies criteria (2) above), so any values registered via this mechanism can be safely retrieved at interrupt time via the standard Gestalt mechanism.
  30.  
  31. Interface
  32.  
  33. Pascal:
  34.  
  35. FUNCTION NewGestaltValue(selector: OSType;newValue: LONGINT): OSErr;
  36. FUNCTION ReplaceGestaltValue(selector: OSType;replacementValue: LONGINT): OSErr;
  37. FUNCTION DeleteGestaltValue(selector: OSType): OSErr;
  38.  
  39. C:
  40.  
  41. pascal OSErr NewGestaltValue (OSType selector, long newValue);
  42. pascal OSErr ReplaceGestaltValue (OSType selector, long replacementValue);
  43. pascal OSErr DeleteGestaltValue (OSType selector);
  44.  
  45. NewGestaltValue and ReplaceGestaltValue are analogous to NewGestalt and ReplaceGestalt.  They take a standard 4 character OSType value and a new or replacement value.  ReplaceGestaltValue has no parameter analogous to the oldGestaltFunction parameter of ReplaceGestalt.  If you desire saving the previous value, you should call Gestalt for that selector before calling ReplaceGestaltValue.
  46.  
  47. The usual restrictions on the selector parameter still apply.  Apple recommends you use your four-character creator sequence for your selector.  All lowercase letter and nonalphabetic ASCII sequences are reserved for Apple.
  48.  
  49. DeleteGestaltValue makes a Gestalt value unknown to Gestalt.  Subsequent calls to Gestalt for that selector will return gestaltUndefSelectorErr.
  50.  
  51. Return values
  52.  
  53. GestaltValue requires that the _Gestalt trap be implemented.  You will get unimpErr (-4) if _Gestalt is unavailable.
  54.  
  55. NewGestaltValue returns gestaltDupSelectorErr (-5552) if you attempt to add a new value for an existing selector.  You should use ReplaceGestaltValue instead.
  56.  
  57. ReplaceGestaltValue returns gestaltUndefSelectorErr (-5551) if you attempt to replace a non-existent selector.  You should use NewGestaltValue instead.
  58.  
  59. Both NewGestaltValue and ReplaceGestalt value may return memory errors if they cannot allocate sufficient room in the system heap for their code and data.
  60.  
  61. DeleteGestaltValue returns gestaltUndefSelectorErr if you attempt to delete a selector unknown to GestaltValue (such as a pre-defined gestalt selector such as 'fpu '.